<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Implementing your own data model: GNOME Data Access 5 manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GNOME Data Access 5 manual">
<link rel="up" href="data_models.html" title="Data handling">
<link rel="prev" href="libgda-5.0-GdaDataComparator.html" title="GdaDataComparator">
<link rel="next" href="trees.html" title="Trees">
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="data_models.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="libgda-5.0-GdaDataComparator.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="trees.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="gda-data-model-writing"></a>Implementing your own data model</h2></div></div></div>
<p>
    You may need at some point to implement your own data model because the implementations in
    <span class="application">Libgda</span> don't suit your needs. This section is dedicated to explaining to you how this can be done.
  </p>
<p>
    Implementing a new <a class="link" href="GdaDataModel.html" title="GdaDataModel">GdaDataModel</a> is simply a matter of
    creating a new GObject which implements the <a class="link" href="GdaDataModel.html" title="GdaDataModel">GdaDataModel</a>
    interface, which is described below. Thos new class needs to inherit GObject, but needs not
    be direct descendant of it. The way to subclass an object using GLib
    is not covered in this documentation, for this matter reref to
    GObject's documentation, or
    <a class="ulink" href="http://developer.gnome.org/gobject/stable/howto-gobject.html" target="_top">online</a>.
  </p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="gda-data-model-writing-virtual-methods"></a>Virtual methods</h3></div></div></div>
<p>
      The interface's methods which can and/or need to be implemented are defined below.
    </p>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_n_rows"></a>i_get_n_rows() - optional</h4></div></div></div>
<p>This method, if implemented, returns the total number of rows in the data model, or -1 if
      unknown. If it's not implemented, then it is assumed that -1 is returned in all cases.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_n_columns"></a>i_get_n_columns() - required</h4></div></div></div>
<p>This method, returns the total number of columns in the data model, or -1 if unknown.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_describe_column"></a>i_describe_column() - required</h4></div></div></div>
<p>This method describes a column; it returns (without any ownership to the caller) a
      <a class="link" href="GdaColumn.html" title="GdaDataModel columns">GdaColumn</a> for each existing column, or NULL otherwise.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_access_flags"></a>i_get_access_flags() - required</h4></div></div></div>
<p>This method defines how the data model may be accessed (randomly, only using a cursor, ...)</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_value_at"></a>i_get_value_at() - required for random access</h4></div></div></div>
<p>This method is used to access the contents of a data model, specifically
      a <a href="/usr/share/gtk-doc/html/gobject/gobject-Generic-values.html#GValue-struct">GValue</a> is returned for each (column,row) position.
      It must return NULL if the data model experienced an error for the specific (column,row)
      position. See <a class="link" href="GdaDataModel.html#gda-data-model-get-value-at" title="gda_data_model_get_value_at ()">gda_data_model_get_value_at()</a>
      for more information about the lifetime of the returned GValue.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_attributes_at"></a>i_get_attributes_at() - optional</h4></div></div></div>
<p>This method returns, for a (column,row) position in the data model, the attributes
      of the adressed "cell".</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_create_iter"></a>i_create_iter() - optional</h4></div></div></div>
<p>This method can be implemented to create specific
      <a class="link" href="GdaDataModelIter.html" title="GdaDataModelIter">GdaDataModelIter</a> or to customize them.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_iter_at_row"></a>i_iter_at_row() - optional</h4></div></div></div>
<p>This method can be implemented if a specific implementation allows an iterator
      to be moved quickly to a specific row (faster than iterating from row to row to the
      requested row).</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_iter_next"></a>i_iter_next() - required for cursor based access</h4></div></div></div>
<p>This method is called to move an iterator to the next row; it's not necessary to
      implement it if the data models supports random access.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_iter_prev"></a>i_iter_prev() - optional for cursor based access</h4></div></div></div>
<p>This method is called to move an iterator to the previous row. It is only necessary to
      implement it if the data model does not support random access and supports moving the
      cursor backward.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_set_value_at"></a>i_set_value_at() - optional</h4></div></div></div>
<p>This method needs to be defined if the data model allows each value in a (column,row) position
      to be modified individually.
      </p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_iter_set_value"></a>i_iter_set_value() - optional</h4></div></div></div>
<p>This method can be defined if a specific treatment is required when a modification made
      to a <a class="link" href="GdaDataModelIter.html" title="GdaDataModelIter">GdaDataModelIter</a> is propagated to the data model.
      It should seldom, if ever, be necessary to implement it.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_set_values"></a>i_set_values() - optional</h4></div></div></div>
<p>This method needs to be defined if the data model allows modifications to be made for
      one complete row at a time. See the
      <a class="link" href="GdaDataModel.html#gda-data-model-set-values" title="gda_data_model_set_values ()">gda_data_model_set_values()</a> method for
      more information about the arguments</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_append_values"></a>i_append_values() - optional</h4></div></div></div>
<p>This method can be implemented if the data model needs to support adding a row and defining the
      values to be added in the same operation.
      See <a class="link" href="GdaDataModel.html#gda-data-model-append-values" title="gda_data_model_append_values ()">gda_data_model_append_values()</a> for
      more information.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_append_row"></a>i_append_row() - optional</h4></div></div></div>
<p>This method needs to be defined if the data model needs to support adding an empty row (i.e.
      without any value specified in the new row).</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_remove_row"></a>i_remove_row() - optional</h4></div></div></div>
<p>This method should be implemented if the data model needs to support row removal.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_find_row"></a>i_find_row() - optional</h4></div></div></div>
<p>This method can be implemented if the data model implements an indexing scheme which
      allows it to find rows from values quickly than by analysing each row after another to
      find the requested values.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_set_notify"></a>i_set_notify() - optional</h4></div></div></div>
<p>This method should be implemented if the data model needs to honor the
      <a class="link" href="GdaDataModel.html#gda-data-model-freeze" title="gda_data_model_freeze ()">gda_data_model_freeze()</a> and
      <a class="link" href="GdaDataModel.html#gda-data-model-thaw" title="gda_data_model_thaw ()">gda_data_model_thaw()</a> methods. If
      this method is not implemented, then these two methods will have no effect.
      </p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_notify"></a>i_get_notify() - optional</h4></div></div></div>
<p>This method should be implemented if the data model needs to honor the
      <a class="link" href="GdaDataModel.html#gda-data-model-freeze" title="gda_data_model_freeze ()">gda_data_model_freeze()</a> and
      <a class="link" href="GdaDataModel.html#gda-data-model-thaw" title="gda_data_model_thaw ()">gda_data_model_thaw()</a> methods. If
      this method is not implemented, then these two methods will have no effect.</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_send_hint"></a>i_send_hint() - optional</h4></div></div></div>
<p>This method should be implemented if the data model needs to be able to treat
      hints, see <a class="link" href="GdaDataModel.html#gda-data-model-send-hint" title="gda_data_model_send_hint ()">gda_data_model_send_hint()</a> for
      more information</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="i_get_exceptions"></a>i_get_exceptions() - optional</h4></div></div></div>
<p>This method needs to be implemented if the data model keeps exceptions about the errors
      it has encountered and may "export" these exceptions using the
      <a class="link" href="GdaDataModel.html#gda-data-model-get-exceptions" title="gda_data_model_get_exceptions ()">gda_data_model_get_exceptions()</a> method.</p>
</div>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="gda-data-model-writing-signalling"></a>Signalling changes</h3></div></div></div>
<p>
      When the data model changes, it needs to signal its changes. However, only the changes from
      the initial state need to be notified, in situations such as:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>a row which has already been accessed is modified or removed</p></li>
<li class="listitem"><p>the total number of rows changes, and that number has already been obtained and
	was known (i.e. different than -1)</p></li>
</ul></div>
<p>
    </p>
<p>
      To signal changes, one of the following methods has to be used:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><a class="link" href="GdaDataModel.html#gda-data-model-row-inserted" title="gda_data_model_row_inserted ()">gda_data_model_row_inserted()</a>: to be called after a row has been inserted</p></li>
<li class="listitem"><p><a class="link" href="GdaDataModel.html#gda-data-model-row-updated" title="gda_data_model_row_updated ()">gda_data_model_row_updated()</a>: to be called after a row has been updated</p></li>
<li class="listitem"><p><a class="link" href="GdaDataModel.html#gda-data-model-row-removed" title="gda_data_model_row_removed ()">gda_data_model_row_removed()</a>: to be called after a row has been removed</p></li>
<li class="listitem"><p><a class="link" href="GdaDataModel.html#gda-data-model-reset" title="gda_data_model_reset ()">gda_data_model_reset()</a>: to be called
	when the data model has changed in a way it's not possible or desirable to signal all the changes
	using any combination of the above methods (for example when the whole contents has changed, or
	when the number and/or types of columns has changed)</p></li>
</ul></div>
<p>
    </p>
<p>
      Moreover, when the data model's access flags have changed, the implementation should signal it by
      emitting the <a class="link" href="GdaDataModel.html#GdaDataModel-access-changed" title="The “access-changed” signal">"access-changed"</a> signal.
    </p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>